/*
 * Copyright (c) 2017  STMicroelectronics – All rights reserved
 * The STMicroelectronics corporate logo is a trademark of STMicroelectronics
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this list of conditions
 *   and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright notice, this list of
 *   conditions and the following disclaimer in the documentation and/or other materials provided
 *   with the distribution.
 *
 * - Neither the name nor trademarks of STMicroelectronics International N.V. nor any other
 *   STMicroelectronics company nor the names of its contributors may be used to endorse or
 *   promote products derived from this software without specific prior written permission.
 *
 * - All of the icons, pictures, logos and other images that are provided with the source code
 *   in a directory whose title begins with st_images may only be used for internal purposes and
 *   shall not be redistributed to any third party or modified in any way.
 *
 * - Any redistributions in binary form shall not include the capability to display any of the
 *   icons, pictures, logos and other images that are provided with the source code in a directory
 *   whose title begins with st_images.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 */

package com.st.BlueMS.demos.Audio.SpeechToText.ASRServices;

import android.app.DialogFragment;
import android.content.Context;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;

import com.st.BlueMS.demos.Audio.SpeechToText.util.DialogFragmentDismissCallback;
import com.st.BlueMS.demos.Audio.Utils.AudioBuffer;

/**
 * Interface which defines a generic ASR Engine
 */
public interface ASREngine {

    /**
     * It reveals if this engine needs an authentication key or not.
     * @return true if this service needs an activation key, false otherwise.
     */
    boolean needAuthKey();

    /**
     * It reveals if this engine has already loaded an authentication key or not.
     * @return true if this service has loaded an activation key, false otherwise.
     */
    boolean hasLoadedAuthKey();

    /**
     * It provide a dialog for ASR key insertion.
     * @return a {@link DialogFragment} which allows the insertion of the
     * ASR service activation key. It return null if the service doesn't need any key.
     */
    @Nullable
    DialogFragmentDismissCallback getAuthKeyDialog();

    /**
     * It allows to make an audio recognition request of the {@code audio}
     * provided as parameter. The result should be returned using {@code callback}
     * which is a {@link ASRRequestCallback}.
     * @param audio It contains the audio you want to be recognized.
     * @param callback a callback used to catch the response.
     * @return true is request is correctly done, false otherwise.
     */
    boolean sendASRRequest(AudioBuffer audio, ASRRequestCallback callback);

    /**
     * It reveals if this engine has a continuous recognizer or not.
     * @return true if this engine implements a continuous speech recognition service,
     * false otherwise.
     */
    boolean hasContinuousRecognizer();

    /**
     * Start the recognizer listener, call the {@link ASRConnectionCallback#onEngineStart()} when the engine
     * stop
     */
    void startListener(@NonNull ASRConnectionCallback callback);

    /**
     * Stop the recognizer listener, call the {@link ASRConnectionCallback#onEngineStop()} when the engine
     * stop
     * @param callback
     */
    void stopListener(@NonNull ASRConnectionCallback callback);

    /**
     * Destroy the recognizer listener
     */
    void destroyListener();

    ASREngineDescription getDescription();

    /**
     * interface used to notify the ASR engine status
     */
    interface ASRConnectionCallback {
        /**
         * callback called when the engine is correctly initialized and started
         */
        void onEngineStart();

        /**
         * callback called when some error happen during the engine initialization or stopping
         * @param e error happen
         */
        void onEngineFail(Throwable e);

        /**
         * callback called when the engine correctly stop
         */
        void onEngineStop();
    }

    interface ASREngineDescription{

        /**
         * Engine name shown to the user
         * @return engine name
         */
        String getName();

        /**
         * Get the list of supported language by the service
         * @return list of supported language
         */
        @ASRLanguage.Language int[] getSupportedLanguage();

        @Nullable
        ASREngine build(@NonNull Context context, @ASRLanguage.Language int language);
    }

}
